feat(keymap)!: replace expr keymaps with normalized feedkeys execution by soifou · Pull Request #2266 · saghen/blink.cmp

soifou · 2025-11-21T16:55:08Z

Revamp keymap handling by moving away from expr mappings to a normalized feedkeys approach, fixing several long-standing edge cases around multi-key mappings, fallbacks, and interoperability with other plugins.

Handle multi-key sequences

{
    ['jk'] = { 'hide', 'fallback' },
    ['<C-x><C-o>'] = { 'show', 'fallback' },
    ['<Leader>cc'] = { 'show', 'fallback' },
}

Preserve key special notation when fallback

vim.keymap.set('i', '<C-i>', function() vim.print('fallback to <C-i>') end, { unique = false })
vim.keymap.set('i', '<Tab>', function() vim.print('fallback to <Tab>') end, { unique = false })
vim.keymap.set('i', '<C-m>', function() vim.print('fallback to <C-m>') end, { unique = false })

{       
    ['<C-i>'] = { 'accept', 'snippet_forward', 'fallback' }, -- when fall back prints "fallback to <C-i>"
    ['<C-m>'] = { 'accept', 'fallback' }, -- when fall back prints "fallback to <C-m>"
}

Key composition

{
    ['<C-n>'] = { 'select_next' },
    ['<Tab>'] = {
       function() return '' end, -- would fallback
       function() return '<C-n>' end, -- would call `select_next`
    },
},

Recursive keymap

vim.keymap.set('i', '<F2>', '<Esc>:echo "Hello from F2"<CR>a', { noremap = true, silent = true })
{
   ['<Space><Space>'] = { function() return '<F2>' end }, -- would print "Hello from F2"
}

Handle script mappings correctly: <SNR>, <SID>, <Plug>

vim.cmd([[
  function! s:MyFunction()
    echo "script local function invoked"
  endfunction

  nnoremap <silent> <SNR>42_mykey :call <SID>MyFunction()<CR>
  nnoremap <silent> <Plug>(MyPlug) :echo "Plug mapping triggered"<CR>
]])

{
    ['<Leader>m'] = { function() return '<Esc><Plug>(MyPlug)a' end }, -- prints "Plug mapping triggered"
}

Handle remap mappings correctly
Apply blink.cmp keymaps eagerly when triggering snippets from normal mode
Reapply blink.cmp keymaps if stolen by others
Refactoring:
- Consolidate and keep the keymap module as simply as possible
- Don't rely anymore on expr,
- Drop vim.schedule in all commands and return boolean value from the function itself
Documentation: Revamp the keymap section

Closes #406
Closes #453
Closes #714
Closes #1879
Closes #2119
Closes #2164
Closes #2182
Closes #2263
Closes #2333
Closes #2384

saghen · 2025-11-21T19:08:00Z

Does calling feedkeys have any caveats that we should be aware of? If not, I'd like to adopt it for all the keymaps! Avoiding expr = true would avoid having to vim.schedule anything that edits the buffer, which would be great for scriptability. I don't mind the way you're detecting multi-key mappings but it would be great if there was a less hacky way (maybe replace_keycodes could help?)

soifou · 2025-11-22T18:57:42Z

Thanks for the feedback, you give me some additional thinking! I'd like to explore this approach a bit more. The feedkeys solution does seem cleaner and we could get rid of multi-key detection if we turn off expr.

Edit: Updated PR description

saghen · 2025-11-25T21:55:29Z

Wow this is quite a bit of work, you'd end up fixing all the major issues with keymaps! These changes would be breaking, since theyre no longer vim.schedule so it might make sense to artificially vim.schedule or merge this into a new v2 branch.

Fyi, I got a bit ambitious with v2 so I'm going to reduce its scope. Just planning some light refactoring, these keymap changes, source-per-LSP, adopt blink.lib, and the improved API (for keymaps, enable, vim.g, dynamic config, etc)

soifou · 2025-11-25T22:24:25Z

Yeah, as long as I'm here, I might as well fix these issues once and for all. I've had promising results locally. I don't mind working on this for v2, but last time I switched to this branch, everything was so broken that it was hard to make any convincing commits. Feel free to keep in touch on Matrix to coordinate!

saghen

This is some brilliant work, thank you so much! Going to start daily driving this

saghen · 2026-03-10T20:28:28Z

Lmk if you're happy with it and I'll merge it after the next release (release after 1.10 will be 2.0)

soifou · 2026-03-11T12:34:26Z

Lmk if you're happy with it and I'll merge it after the next release (release after 1.10 will be 2.0)

Yes, this seems stable enough!

Note I was initially hesitant about 2bf5cf8 due to your comment, so I focused only on the keymap module. This commit closes #2333, #2381 (~~with minor updates~~), and #2384. But will this still break existing user configs? I'm still not sure.

Before merging, we need to:

Update the keymap documentation to reflect these changes
~~Link all closed issues~~
Decide whether it will break configs

Overall, I'm super excited to see this on your radar and see it land!

This change introduces: - multi-key sequence support (e.g. `<C-x><C-o>`) - normalized key comparison and equivalence (`<C-i>` == `<Tab>`) - key composition from user callbacks - fallback handling, including `<Plug>`, `<SID>`, and script mappings - automatic reapplication of missing (stolen) buffer keymaps Keymaps are now buffer-local for all modes, rely on normalized key notation instead of termcodes, and execute commands eagerly until one succeeds. BREAKING CHANGE: Keymap execution semantics, fallback behavior, and mapping scope have changed. expr mappings are no longer used.

Script-function tokens were parsed using keycode grammar

Also move `can_select` check into `completion.list.select_next/prev` so the selection functions are self-contained.

saghen · 2026-03-13T16:05:13Z

Decide whether it will break configs

Yeah I initially wanted to wait for v2, but I'm about to make the 1.10 release and next will be 2.0, so we can begin making breaking changes

soifou · 2026-03-13T16:14:56Z

Excellent, I was worried things were getting too stable!

saghen · 2026-03-13T17:11:34Z

Gotta give the people something to tinker with in their config 😂

saghen · 2026-03-14T21:33:19Z

Merging without the documentation changes because I want to start the bigger refactors, but don't want to cause tons of merge conflicts for ya. Can't say it enough, brilliant work on this

Revamped the keymap documentation to align with recent API changes introduced in #2266.

Revamped the keymap documentation to align with recent API changes introduced in #2266. --------- Co-authored-by: Liam Dyer <liamcdyer@gmail.com>

This comment was marked as outdated.

Sign in to view

soifou changed the title ~~fix(keymap): handle multi-key mappings correctly~~ refactor(keymap): improve fallback and key handling Nov 24, 2025

soifou marked this pull request as draft November 24, 2025 18:27

soifou mentioned this pull request Dec 4, 2025

{ "select_accept_and_enter", "fallback" } Does not trigger abbreviations in cmdline #2263

Closed

2 tasks

soifou force-pushed the fix/keymap-multikey branch 4 times, most recently from fec6db0 to c855892 Compare December 22, 2025 13:48

soifou changed the title ~~refactor(keymap): improve fallback and key handling~~ feat(keymap)!: replace expr keymaps with normalized feedkeys execution Dec 22, 2025

soifou force-pushed the fix/keymap-multikey branch from c855892 to d080c78 Compare February 6, 2026 01:20

soifou mentioned this pull request Feb 6, 2026

rapid repeat select_next sometimes break the completion #2384

Closed

soifou force-pushed the fix/keymap-multikey branch from d080c78 to 530299a Compare February 7, 2026 12:13

This comment was marked as resolved.

Sign in to view

soifou force-pushed the fix/keymap-multikey branch from c3a2351 to b784f83 Compare February 14, 2026 16:41

saghen reviewed Mar 2, 2026

View reviewed changes

Comment thread lua/blink/cmp/keymap/init.lua

Comment thread lua/blink/cmp/keymap/init.lua Outdated

saghen force-pushed the fix/keymap-multikey branch from 83c8837 to f4ec48f Compare March 10, 2026 20:27

saghen marked this pull request as ready for review March 10, 2026 20:27

saghen force-pushed the fix/keymap-multikey branch from f4ec48f to e42586f Compare March 10, 2026 20:34

soifou added 3 commits March 13, 2026 13:14

fix(keymap): apply on nt:c transition

cd390f1

fix: prevent infinite recursion for script-local <expr> mappings

a739d63

soifou and others added 5 commits March 13, 2026 13:14

fix: correctly parse script-function token

5edf1d6

Script-function tokens were parsed using keycode grammar

feat: drop vim.schedule on keymaps/commands

5c696b8

docs: fix keymap example missing return

ed40c01

style: doc comment spacing and triple dash

c5be9d7

feat: make scroll APIs return whether scrolling actually occurred

288a776

soifou force-pushed the fix/keymap-multikey branch from dadb6a1 to 288a776 Compare March 13, 2026 12:31

soifou added 4 commits March 13, 2026 14:57

fix: return actual selection result instead of always true

b30afc2

Also move `can_select` check into `completion.list.select_next/prev` so the selection functions are self-contained.

refactor(snippets): make jump() return boolean and propagate result

b5f1cf5

refactor: normalize api actions to return boolean

63fe4b2

chore: set correct annotation

037bc55

saghen merged commit af18529 into main Mar 14, 2026
6 checks passed

saghen deleted the fix/keymap-multikey branch March 14, 2026 21:33

saghen mentioned this pull request Mar 16, 2026

scroll function should return if the content can be scrolled #2381

Closed

PFiS1737 mentioned this pull request Mar 17, 2026

[Bug] keymap.preset = "enter" interferes with ultimate-autopair.nvim newline expansion on <CR> #2449

Closed

2 tasks

soifou added a commit that referenced this pull request Mar 31, 2026

doc: rewrite keymap section

f380b70

Revamped the keymap documentation to align with recent API changes introduced in #2266.

soifou mentioned this pull request Mar 31, 2026

doc: rewrite keymap section #2460

Merged

saghen added a commit that referenced this pull request Apr 1, 2026

doc: rewrite keymap section (#2460)

9d269cd

Revamped the keymap documentation to align with recent API changes introduced in #2266. --------- Co-authored-by: Liam Dyer <liamcdyer@gmail.com>

soifou mentioned this pull request Apr 10, 2026

Shortcut fallbacks emmiting the wrong keybind #2488

Closed

2 tasks

Conversation

soifou commented Nov 21, 2025 • edited by saghen Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

saghen commented Nov 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

soifou commented Nov 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

saghen commented Nov 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

soifou commented Nov 25, 2025

Uh oh!

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

This comment was marked as resolved.

saghen left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

saghen commented Mar 10, 2026

Uh oh!

soifou commented Mar 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

saghen commented Mar 13, 2026

Uh oh!

soifou commented Mar 13, 2026

Uh oh!

saghen commented Mar 13, 2026

Uh oh!

saghen commented Mar 14, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

soifou commented Nov 21, 2025 •

edited by saghen

Loading

saghen commented Nov 21, 2025 •

edited

Loading

soifou commented Nov 22, 2025 •

edited

Loading

saghen commented Nov 25, 2025 •

edited

Loading

soifou commented Mar 11, 2026 •

edited

Loading